Copyright ã1995 by NeXT Computer, Inc.  All Rights Reserved.

NS_DEV_DOCFOR:objc_class:Button;,Button

Inherits From:	Control : View : Responder : Object

Declared In:	appkit/Button.h

Class Description

Button is a subclass of Control that intercepts mouse-down events and sends an action message to a target object when it's clicked or pressed.  By virtue of its ButtonCell, Button is a two-state ControlÐit's either ªoffº or ªonºÐand it displays its state depending on the configuration of the ButtonCell.  Button acquires other attributes of ButtonCell.  The state is used as the value, so Control methods like setIntValue: actually set the state (the methods setState: and state are provided for more conceptually accurate setting of the state).  The Button can send its action continuously and display highlighting in several different ways.  What's more, a Button can have a key equivalent that's eligible for triggering whenever the Button's Panel or Window is key.

Button and Matrix both provide a Control View needed to display a ButtonCell object.  However, while Matrix requires you to access the ButtonCells directly, most of Button's methods are covers for identically declared methods in ButtonCell.  The only ButtonCell methods that don't have covers relate to the font used to display the key equivalent, and to specific methods for highlighting or showing the Button's state (these last are usually set together with Button's setType: method).

Creating a Subclass of Button

The initFrame:icon:tag:target:action:key:enabled: method is the designated initializer for Buttons that initially display only icons.  Buttons that initially display only text have the designated initializer initFrame:text:tag:target:action:key:enabled:.  Override one or both of these methods if you create a subclass of Button that performs its own initialization.

In particular, if you want to use a custom ButtonCell subclass with your subclass of Button, you have to override the setCellClass: method as well as the designated initializers, as described in ªCreating New Controlsº in the Control class specification.

See the ButtonCell class specification for more on Button's behavior.  

Instance Variables

None declared in this class.

Method Types

Setting Button's Cell class	+ setCellClass:

Initializing a Button	- init
- initFrame:
- initFrame:icon:tag:target:action:key:enabled:
- initFrame:title:tag:target:action:key:enabled:

Setting the Button type	- setType:

Setting the state	- setState:
- state

Setting the repeat interval	- setPeriodicDelay:andInterval:
- getPeriodicDelay:andInterval:

Setting the titles	- setTitle:
- setTitleNoCopy:
- title
- setAltTitle:
- altTitle

Setting the icons	- setIcon:
- setIcon:position:
- icon
- setAltIcon:
- altIcon
- setImage:
- image
- setAltImage:
- altImage
- setIconPosition:
- iconPosition

Modifying graphic attributes	- setTransparent:
- isTransparent
- setBordered:
- isBordered

Displaying the Button	- display
- highlight:

Setting the key equivalent	- setKeyEquivalent:
- keyEquivalent

Handling events and action messages 
- acceptsFirstMouse
- performClick:
- performKeyEquivalent:

Setting the Sound	- setSound:
- sound

Class Methods

NS_DEV_DOCFOR:objc_method:[Button-setCellClass:];,setCellClass:

+ setCellClass:classId

Configures the Button class to use instances of classId for its Cells.  classId should be the id of a subclass of ButtonCell, obtained by sending the class message to either the Cell subclass object or to an instance of that subclass.  The default Cell class is ButtonCell.  Returns self.

If this method isn't overridden by a subclass of Button, then when it's sent to that subclass,  Button and any other subclasses of Button that don't override the methods mentioned below will use the new Cell subclass as well.  To safely set a Cell class for your subclass of Button, override this method to store the Cell class in a static id.  Also, override the designated initializer to replace the Button subclass instance's Cell with an instance of the Cell subclass stored in that static id.  See ªCreating New Controlsº in the Control class specification's class description for more information.

Instance Methods

NS_DEV_DOCFOR:objc_method:[Button-acceptsFirstMouse];,acceptsFirstMouse

- (BOOL)acceptsFirstMouse

Returns YES.  Buttons always accept the mouse-down event that activates a Window, regardless of whether the Button is enabled.

NS_DEV_DOCFOR:objc_method:[Button-altIcon];,altIcon

- (const char *)altIcon

Returns the name of the NXImage that appears on the Button when it's in its alternate state, or NULL if there is no alternate icon or the NXImage has no name.  This NXImage is displayed only for Buttons that highlight or show their alternate state by displaying their alternate contents (as opposed to simply lighting or pushing in).

See also:  - setAltIcon:, - setIconPosition:, - altImage, - icon, - image, - setType:

NS_DEV_DOCFOR:objc_method:[Button-altImage];,altImage

- altImage

Returns the NXImage that appears on the Button when it's in its alternate state, or nil if there is no alternate NXImage.  This Button only displays its alternate NXImage if it highlights or shows its alternate state by displaying its alternate contents.

See also:  - setAltImage:, - setIconPosition:, - altIcon, - image, - icon, - setType:

NS_DEV_DOCFOR:objc_method:[Button-altTitle];,altTitle

- (const char *)altTitle

Returns the string that appears on the Button when it's in its alternate state, or NULL if there isn't one.  The alternate title is only displayed if the Button highlights or shows its alternate state by displaying its alternate contents.

See also:  - setAltTitle:, - title, - setType:

NS_DEV_DOCFOR:objc_method:[Button-display];,display

- display

Displays the Button.  This method is overridden from View so that displayFromOpaqueAncestor::: is invoked if the Button is not opaque.  Returns self.

See also:  - isOpaque (Cell), - isTransparent, - setTransparent:

NS_DEV_DOCFOR:objc_method:[Button-getPeriodicDelay:andInterval:];,getPeriodicDelay:andInterval:

- getPeriodicDelay:(float *)delay andInterval:(float *)interval

Returns self, and by reference the delay and interval periods for a continuous Button.  delay is the amount of time (in seconds) that a continuous  Button will pause before starting to periodically send action messages to the target object.  interval is the amount of time (also in seconds) between those messages.

See also:  - setContinuous: (Control), - setPeriodicDelay:andInterval:

NS_DEV_DOCFOR:objc_method:[Button-highlight:];,highlight:

- highlight:(BOOL)flag

If the highlight state of the cell is not equal to flag, the Button is highlighted and the highlight state of the cell is set to flag.  Highlighting may involve the Button appearing ªpushed inº to the screen, displaying its alternate title or icon, or lighting.  This method issues a flushWindow message after highlighting the Button.  Returns self.

See also:  - setType:

NS_DEV_DOCFOR:objc_method:[Button-icon];,icon

- (const char *)icon

Returns the name of the NXImage that appears on the Button when it's in its normal state, or NULL if there is no such NXImage or the NXImage doesn't have a name.  A Button that doesn't display its alternate contents to highlight or show its alternate state will always display its normal icon.

See also:  - setIcon:, - setIcon:position:, - setIconPosition:, - image, - altIcon, - altImage, - setType:

NS_DEV_DOCFOR:objc_method:[Button-iconPosition];,iconPosition

- (int)iconPosition

Returns the position of the icon (if any) on the Button.  See setIconPosition: for the list of positions.

See also:  - setIconPosition:, - setIcon:position:

NS_DEV_DOCFOR:objc_method:[Button-image];,image

- image

Returns the NXImage that appears on the Button when it's in its normal state, or nil if there is no such NXImage.  This NXImage is always displayed on a Button that doesn't change its contents when highlighting or showing its alternate state.

See also:  - setImage:, - setIconPosition:, - icon, - altImage, - altIcon, - setType:

NS_DEV_DOCFOR:objc_method:[Button-init];,init

- init

Initializes and returns the receiver, a new Button instance, with a frame origin of (0, 0) and width and height of 50 units each.  The new instance is enabled and displays the default title ªButtonº centered in its frame, but has no icon, tag, target, action, or key equivalent associated with it.  The new Button is bordered, and is of type NX_MOMENTARYPUSH.  One of the more specific initializers is usually used to initialize a Button.

See also:  - initFrame:title:tag:target:action:key:enabled:, - initFrame:icon:tag:target:action:key:enabled:, - initFrame:, - setType:

NS_DEV_DOCFOR:objc_method:[Button-initFrame:];,initFrame:

- initFrame:(const NXRect *)frameRect

Initializes and returns the receiver, a new Button instance, with default parameters in the given frame.  The new instance is enabled and displays the default title ªButtonº centered in its frame, but has no icon, tag, target, action, or key equivalent.  The new Button is bordered, and is of type NX_MOMENTARYPUSH.  One of the more specific initializers is usually used to initialize a Button.

See also:  - initFrame:title:tag:target:action:key:enabled:, - initFrame:icon:tag:target:action:key:enabled:, - initFrame:, - setType:

NS_DEV_DOCFOR:objc_method:[Button-initFrame:icon:tag:target:action:key:enabled:];,initFrame:icon:tag:target:action:key:enabled:

- initFrame:(const NXRect *)frameRect
icon:(const char *)iconName
tag:(int)anInt
target:anObject
action:(SEL)aSelector
key:(unsigned short)charCode
enabled:(BOOL)flag

Initializes and returns the receiver, a new Button instance that displays an icon.  frameRect is the rectangle defining the Button's position and size in its superview.  iconName is the name of an NXImage that will be used for the Button's icon.  anInt is set as the Button's tag.  anObject is set as the target, which will be sent aSelector when the Button is clicked or pressed.  charCode is the new Button's key equivalent.  flag determines whether the Button is enabled or not.  The new Button is bordered, and is of type NX_MOMENTARYPUSH.

This method is the designated initializer for Buttons that display icons.  A Button that displays an icon can be configured to also display a title with the setTitle: and setIconPosition: methods.

See also:  - setTitle:, - setIconPosition:, - setType:

NS_DEV_DOCFOR:objc_method:[Button-initFrame:title:tag:target:action:key:enabled:];,initFrame:title:tag:target:action:key:enabled:

- initFrame:(const NXRect *)frameRect
title:(const char *)aString
tag:(int)anInt
target:anObject
action:(SEL)aSelector
key:(unsigned short)charCode
enabled:(BOOL)flag

Initializes and returns the receiver, a new Button instance that displays a text string.  The arguments and operation of this method are identical to those of initFrame:icon:tag:target:action:key:enabled:, except that aString is the title that the Button will display instead of the name of an icon.  The new Button is bordered, and is of type NX_MOMENTARYPUSH.

This method is the designated initializer for Buttons that display text.  A Button that displays an icon can be configured to also display an icon with the setIcon:position: method, or a combination of setIcon: or setImage: and setIconPosition:.

See also:  - setIcon:, - setImage:, - setIconPosition:, - setType:

NS_DEV_DOCFOR:objc_method:[Button-isBordered];,isBordered

- (BOOL)isBordered

Returns YES if the Button has a border, NO otherwise.  A Button's border isn't the single line of most other Controls' borders; instead, it's a raised bezel (ªbezelº usually refers to a depressed bezel, as seen on FormCells, for example).  You shouldn't use the setBezeled: method with a Button.

See also:  - setBordered:

NS_DEV_DOCFOR:objc_method:[Button-isTransparent];,isTransparent

- (BOOL)isTransparent

Returns YES if the Button is transparent, NO otherwise.  A transparent Button never draws itself, but it receives mouse-down events and tracks the mouse properly.

See also:  - setTransparent:

NS_DEV_DOCFOR:objc_method:[Button-keyEquivalent];,keyEquivalent

- (unsigned short)keyEquivalent

Returns the key equivalent character of the Button, or 0 if one hasn't been defined.

See also:  - setKeyEquivalent:, - performKeyEquivalent:

NS_DEV_DOCFOR:objc_method:[Button-performClick:];,performClick:

- performClick:sender

Highlights the Button, sends its action message to the target object, then unhighlights the Button.  Invoke this method when you want the Button to behave exactly as if the user had clicked it with the mouse.

See also:  - performKeyEquivalent:

NS_DEV_DOCFOR:objc_method:[Button-performKeyEquivalent:];,performKeyEquivalent:

- (BOOL)performKeyEquivalent:(NXEvent *)theEvent

If the character in theEvent matches the Button's key equivalent, simulates the user clicking the Button by sending performClick: to self, and returns YES.  Otherwise, does nothing and returns NO.

The Button won't perform the key equivalent if there's a modal panel present that the Button isn't on.

See also:  - keyEquivalent, - performClick:

NS_DEV_DOCFOR:objc_method:[Button-setAltIcon:];,setAltIcon:

- setAltIcon:(const char *)iconName

Sets the Button's alternate icon by name; iconName is the name of the NXImage to be displayed.  Doesn't display the Button even if autodisplay is on.  Returns self.

A Button's alternate icon is only displayed if the Button highlights or shows its alternate state by changing its contents.

See also:  - altIcon, - setIconPosition:, - setAltImage:, - setIcon:, - setImage:, + findImageNamed: (NXImage), - setType:, - setAutodisplay: (View)

NS_DEV_DOCFOR:objc_method:[Button-setAltImage:];,setAltImage:

- setAltImage:altImage

Sets the Button's alternate icon by id; altImage is the NXImage to be displayed.  Returns self.

A Button displays its alternate NXImage only if it highlights or displays its alternate state by using its alternate contents.

See also:  - altImage, - setIconPosition:, - setAltIcon:, - setImage:, - setIcon:, - setType:

NS_DEV_DOCFOR:objc_method:[Button-setAltTitle:];,setAltTitle:

- setAltTitle:(const char *)aString

Sets the title that the Button displays in its alternate state to aString.  Returns self.

The alternate title is shown only if the Button changes its contents when highlighting or displaying its alternate state.

See also:  - altTitle:, - setTitle:, - setType:

NS_DEV_DOCFOR:objc_method:[Button-setBordered:];,setBordered:

- setBordered:(BOOL)flag

If flag is YES, the Button displays a border; if NO, the Button doesn't display a border.  A Button's border is not the single line or most other Controls' borders; instead, it's a raised bezel (ªbezelº usually refers to a depressed bezel, as seen on FormCells, for example).  This method redraws the Button if the bordered state changes.  Returns self.

See also:  - isBordered

NS_DEV_DOCFOR:objc_method:[Button-setIcon:];,setIcon:

- setIcon:(const char *)iconName

Sets the Button's icon by name; iconName is the name of the NXImage to be displayed.  Redraws the Button's inside and returns self.

A Button's icon is displayed when the Button is in its normal state, or always if the Button doesn't highlight or show state by changing its contents.

See also:  - setIcon:position:, - icon, - setIconPosition:, - setImage:, - setAltIcon:, - setAltImage:, + findImageNamed: (NXImage), - setType:

NS_DEV_DOCFOR:objc_method:[Button-setIcon:position:];,setIcon:position:

- setIcon:(const char *)iconName position:(int)aPosition

Combines setIcon: and setIconPosition: into one message.  Returns self.

See also:  - setIcon:, - setIconPosition:

NS_DEV_DOCFOR:objc_method:[Button-setIconPosition:];,setIconPosition:

- setIconPosition:(int)aPosition

Sets the position of the icon when a Button simultaneously displays both text and an icon.  aPosition can be one of the following constants:

NX_TITLEONLY	title only (no icon on the Button) 
NX_ICONONLY	icon only (no text on the Button) 
NX_ICONLEFT	icon is to the left of the text 
NX_ICONRIGHT	icon is to the right of the text 
NX_ICONBELOW	icon is below the text 
NX_ICONABOVE	icon is above the text 
NX_ICONOVERLAPS	icon and text overlap (text drawn over icon)

If the position is top or bottom, the alignment of the text will be changed to NX_CENTERED.  This behavior can be overridden with a subsequent setAlignment: method.  Redraws the Button's inside and returns self.

See also:  - iconPosition, - setIcon:position:, - setAlignment: (Control)

NS_DEV_DOCFOR:objc_method:[Button-setImage:];,setImage:

- setImage:image

Sets the Button's icon by id; image is the NXImage to be displayed.   Redraws the Button's inside and returns self.

A Button's icon is displayed when the Button is in its normal state, or all the time for a Button that doesn't change its contents when highlighting or displaying its alternate state.

See also:  - image, - setIconPosition:, - setIcon:, - setAltImage:, - setAltIcon:, - setType:

NS_DEV_DOCFOR:objc_method:[Button-setKeyEquivalent:];,setKeyEquivalent:

- setKeyEquivalent:(unsigned short)charCode

Sets the key equivalent character of the Button, and redraws the Button's inside if there is no icon or alternate icon set for the Button.  The key equivalent isn't displayed if the icon position is set to NX_TITLEONLY, NX_ICONONLY or NX_ICONOVERLAPS; that is, the Button must display both its title and its ªiconº (the key equivalent in this case), and they must not overlap.  Returns self.

To display a key equivalent on a Button, set the image and alternate image to nil, then set the key equivalent, and then set the icon position.

See also:  - keyEquivalent, - setIconPosition:, - performKeyEquivalent:, - setImage:, - setAltImage:

NS_DEV_DOCFOR:objc_method:[Button-setPeriodicDelay:andInterval:];,setPeriodicDelay:andInterval:

- setPeriodicDelay:(float)delay andInterval:(float)interval

Sets the message delay and interval for the Button.  These two values are used if the Button is configured (by a setContinuous: message) to continuously send the action message to the target object while tracking the mouse.  delay is the amount of time (in seconds) that a continuous Button will pause before starting to periodically send action messages to the target object.  interval is the amount of time (also in seconds) between those messages.  Returns self.

The maximum value allowed for both the delay and the interval is 60.0 seconds.

See also:  - getPeriodicDelay:andInterval:, - setContinuous (Control)

NS_DEV_DOCFOR:objc_method:[Button-setSound:];,setSound:

- setSound:soundObject

Sets the Sound played when the Button is pressed, and whenever the cursor re-enters the Button while tracking.  Returns self.

See also:  - sound

NS_DEV_DOCFOR:objc_method:[Button-setState:];,setState:

- setState:(int)anInt

Sets the Button's state to anInt and redraws the Button.  0 is the normal or ªoffº state, and any nonzero number is the alternate or ªonº state.  Returns self.

See also:  - state

NS_DEV_DOCFOR:objc_method:[Button-setTitle:];,setTitle:

- setTitle:(const char *)aString

Sets the title displayed by the Button when in its normal state to aString.  This title is always shown on Buttons that don't use their alternate contents when highighting or displaying their alternate state.  Redraws the Button's inside and returns self.

See also:  - setTitleNoCopy:, - title, - setAltTitle:, - setType:

NS_DEV_DOCFOR:objc_method:[Button-setTitleNoCopy:];,setTitleNoCopy:

- setTitleNoCopy:(const char *)aString

Similar to setTitle: but doesn't make a copy of aString.  Returns self.

See also:  - setTitle:

NS_DEV_DOCFOR:objc_method:[Button-setTransparent:];,setTransparent:

- setTransparent:(BOOL)flag

Sets whether the Button is transparent, and redraws the Button if flag is NO.  Returns self.

A transparent Button tracks the mouse and sends its action, but doesn't draw.  A transparent Button is useful for sensitizing an area on the screen so that an action gets sent to a target when the area receives a mouse click.

See also:  - isTransparent

NS_DEV_DOCFOR:objc_method:[Button-setType:];,setType:

- setType:(int)aType

Sets the way the Button highlights while pressed, and how it shows its state.  Redraws the Button and returns self.  The types available are for the most common Button types, which are also accessible in Interface Builder; you can configure different behavior with ButtonCell's setHighlightsBy: and setShowsStateBy: methods.  aType can be one of seven constants:

NX_MOMENTARYPUSH (the default):  While the Button is held down it's shown as lit, and also ªpushed inº to the screen if the Button is bordered.  This type of Button is best for simply triggering actions, as it doesn't show its state; it always displays its normal icon or title.  This option is called ªMomentary Pushº in Interface Builder's Button Inspector.

NX_MOMENTARYCHANGE:  While the Button is pressed, the alternate icon or alternate title is displayed.  This type always displays its normal title or icon (that is, it doesn't display its state).  The miniaturize button in a window's title bar is a good example of this type of Button.  This option is called ªMomentary Changeº in Interface Builder's Button Inspector.

NX_PUSHONPUSHOFF:  Holding the Button down causes it to be shown as lit, and also ªpushed inº to the screen if the Button is bordered.  The Button displays itself as lit while in its alternate state.  This option is called ªPush On/Push Offº in Interface Builder's Button Inspector.

NX_ONOFF:  Highlights while pressed by lighting, and stays lit in its alternate state.  This option is called ªOn/Offº in Interface Builder's Button Inspector.

NX_TOGGLE:  Highlighting is performed by changing to the alternate title or icon ªpushing in.º  The alternate state is shown by displaying the alternate title or icon.  This option is called ªToggleº in Interface Builder's Button Inspector.

NX_SWITCH:  A variant of NX_TOGGLE that has no border, and that has a default icon called ªswitchº and an alternate icon called ªswitchHº (these are identical to the ªNXswitchº and ªNXswitchHº system bitmaps).  This type of Button is available as a separate palette item in Interface Builder.

NX_RADIOBUTTON:  Like NX_SWITCH, but the default icon is ªradioº and the alternate icon is ªradioHº (identical to the ªNXradioº and ªNXradioHº system bitmaps).  This type of Button is available as a separate palette item in Interface Builder.

There is no constant for Interface Builder's ªMomentary Lightº type; you can set this programmatically as follows:

[[myButton cell] setHighlightsBy:NX_CHANGEGRAY | NX_CHANGEBACKGROUND];
[[myButton cell] setShowsStateBy:NX_NONE];

See also:  - setType: (ButtonCell), - setHighlightsBy: (ButtonCell), - setShowsStateBy: (ButtonCell)

NS_DEV_DOCFOR:objc_method:[Button-sound];,sound

- sound

Returns the Sound played when the Button is pressed, and whenever the cursor re-enters the Button while tracking.

See also:  - setSound:

NS_DEV_DOCFOR:objc_method:[Button-state];,state

- (int)state

Returns the Button's state, either 0 for normal or ªoff,º or 1 for alternate or ªon.º

See also:  - setState:

NS_DEV_DOCFOR:objc_method:[Button-title];,title

- (const char *)title

Returns the title displayed on the Button when it's in its normal state, or always if the Button doesn't use its alternate contents for highlighting or displaying the alternate state.  Returns NULL if there is no title.

See also:  - setTitle:, - altTitle, - setType: